home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games: Greatest Hits 1996 / Amiga Games: Greatest Hits 1996.iso / archive / userbox / publicdomain / xfd.lha / xfd / Developper / autodoc / xfdmaster.doc < prev    next >
Text File  |  1996-08-03  |  27KB  |  852 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdmaster.library/xfdAllocBufferInfo
  4. xfdmaster.library/xfdAllocObject
  5. xfdmaster.library/xfdAllocSegmentInfo
  6. xfdmaster.library/xfdDecrunchBuffer
  7. xfdmaster.library/xfdDecrunchSegment
  8. xfdmaster.library/xfdFreeBufferInfo
  9. xfdmaster.library/xfdFreeObject
  10. xfdmaster.library/xfdFreeScanList
  11. xfdmaster.library/xfdFreeSegmentInfo
  12. xfdmaster.library/xfdGetErrorText
  13. xfdmaster.library/xfdInitScanHook
  14. xfdmaster.library/xfdObjectType
  15. xfdmaster.library/xfdRecogBuffer
  16. xfdmaster.library/xfdRecogLinker
  17. xfdmaster.library/xfdRecogSegment
  18. xfdmaster.library/xfdRelocate
  19. xfdmaster.library/xfdScanData
  20. xfdmaster.library/xfdStripHunks
  21. xfdmaster.library/xfdTestHunkStructure
  22. xfdmaster.library/xfdTestHunkStructureFlags
  23. xfdmaster.library/xfdTestHunkStructureNew
  24. xfdmaster.library/xfdUnlink
  25.  
  26. xfdmaster.library/xfdAllocBufferInfo     xfdmaster.library/xfdAllocBufferInfo
  27.  
  28.    NAME
  29.     xfdAllocBufferInfo -- Allocate memory for BufferInfo structure.
  30.  
  31.    SYNOPSIS
  32.     bufferinfo = xfdAllocBufferInfo()
  33.         D0              -30
  34.  
  35.     struct xfdBufferInfo *xfdAllocBufferInfo(void);
  36.  
  37.    FUNCTION
  38.     Allocates a memory block large enough to hold all information of
  39.     the xfdBufferInfo structure.
  40.  
  41.     (V36) This function is obsolete and shouldn't be used with new
  42.     code any longer. Use xfdAllocObject() instead.
  43.  
  44.    INPUTS
  45.     None.
  46.  
  47.    RESULT
  48.     bufferinfo - Pointer to the xfdBufferInfo structure or NULL if
  49.                  there occured an error.
  50.  
  51.    SEE ALSO
  52.     xfdFreeBufferInfo(), xfdFreeObject()
  53.  
  54. xfdmaster.library/xfdAllocObject             xfdmaster.library/xfdAllocObject
  55.  
  56.    NAME
  57.     xfdAllocObject -- Allocate memory for specified object. (V36)
  58.  
  59.    SYNOPSIS
  60.     object = xfdAllocObject(objecttype)
  61.       D0          -114          D0
  62.  
  63.     object *xfdAllocObject(objecttype);
  64.  
  65.    FUNCTION
  66.     Allocates a memory block for the specified object. Never do this in
  67.     any other way for compatibility with library updates.
  68.  
  69.     Objecttype can be one of these:
  70.     XFDOBJ_BUFFERINFO     - allocate a xfdBufferInfo structure.
  71.     XFDOBJ_SEGMENTINFO    - allocate a xfdSegmentInfo structure.
  72.     XFDOBJ_LINKERINFO     - allocate a xfdLinkerInfo structure.
  73.     XFDOBJ_SCANNODE (V37) - allocate a xfdScanNode structure.
  74.  
  75.    INPUTS
  76.     objecttype - One of the XFDOBJ_#? values.
  77.  
  78.    RESULT
  79.     object - Pointer to the object or NULL if there occured an error.
  80.  
  81.    SEE ALSO
  82.     xfdFreeObject()
  83.  
  84. xfdmaster.library/xfdAllocSegmentInfo   xfdmaster.library/xfdAllocSegmentInfo
  85.  
  86.    NAME
  87.     xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure.
  88.  
  89.    SYNOPSIS
  90.     segmentinfo = xfdAllocSegmentInfo()
  91.         D0                -42
  92.  
  93.     struct xfdSegmentInfo *xfdAllocSegmentInfo(void);
  94.  
  95.    FUNCTION
  96.     Allocates a memory block large enough to hold all information of
  97.     the xfdSegmentInfo structure.
  98.  
  99.     (V36) This function is obsolete and shouldn't be used with new
  100.     code any longer. Use xfdAllocObject() instead.
  101.  
  102.    INPUTS
  103.     None.
  104.  
  105.    RESULT
  106.     segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if
  107.                   there occured an error.
  108.  
  109.    SEE ALSO
  110.     xfdFreeSegmentInfo(), xfdFreeObject()
  111.  
  112. xfdmaster.library/xfdDecrunchBuffer       xfdmaster.library/xfdDecrunchBuffer
  113.  
  114.    NAME
  115.     xfdDecrunchBuffer -- Decrunch a file from buffer.
  116.  
  117.    SYNOPSIS
  118.     success = xfdDecrunchBuffer(bufferinfo)
  119.       D0             -60            A0
  120.  
  121.     BOOL xfdDecrunchBuffer(struct xfdBufferInfo *);
  122.  
  123.    FUNCTION
  124.     Decrunches a file to a separate buffer. You have to call
  125.     xfdRecogBuffer() first, only if this call was successful,
  126.     you may call xfdDecrunchBuffer().
  127.  
  128.     You have to pass the type of memory that should be used for
  129.     the target buffer in xfdbi_TargetBufMemType.
  130.     Additionally you have to init the xfdbi_Special field with
  131.     a pointer to a special info buffer if any special flags are
  132.     set in the xfdbi_PackerFlags field:
  133.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  134.                  password is stored in xfdbi_MaxSpecialLen,
  135.                  if this is -1, password is not limited).
  136.     XFDPFB_KEY16 (V35) - xfdbi_Special points to an UWORD that holds
  137.                          a 16 bit key.
  138.     XFDPFB_KEY32 (V35) - xfdbi_Special points to an ULONG that holds
  139.                          a 32 bit key.
  140.  
  141.     If the decrunching was successful, the following fields in
  142.     the xfdBufferInfo structure will be initialized:
  143.  
  144.     xfdbi_TargetBuffer     - Pointer to decrunched file buffer.
  145.     xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.).
  146.     xfdbi_TargetBufLen     - Total length of allocated buffer.
  147.     xfdbi_DecrAddress      - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  148.                              this contains the address where the crunched
  149.                              file has been relocated to.
  150.     xfdbi_JmpAddress       - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  151.                              this contains the address where to jump at
  152.                              in order to run the file.
  153.  
  154.    INPUTS
  155.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  156.        xfdbi_TargetBufMemType - Type of memory for target buffer.
  157.        xfdbi_Special          - Pointer to special info if required.
  158.  
  159.    RESULT
  160.     success - TRUE if decrunching was successful, FALSE if
  161.               anything went wrong.
  162.  
  163.    NOTE
  164.     xfdDecrunchBuffer() allocates a buffer for the decrunched file,
  165.     but it doesn't release this memory afterwards. That is because
  166.     you first have to work with the decrunched file (what else?).
  167.     Therefore you have to do a call to exec.library/FreeMem() after
  168.     you finished work. Use the following parameters:
  169.     xfdbi_TargetBufLen - Lenght of buffer.
  170.     xfdbi_TargetBuffer - Pointer to buffer.
  171.  
  172.     Don't forget:
  173.     xfdbi_TargetBufLen contains the length of the allocated memory
  174.     area, xfdbi_TargetBufSaveLen the length of the decrunched file
  175.     in that buffer.
  176.  
  177.     xfdDecrunchBuffer() never touches the buffer that contains the
  178.     crunched file. It's again your task to release this after
  179.     decrunching.
  180.  
  181.    SEE ALSO
  182.     xfdRecogBuffer(), exec.library/FreeMem()
  183.  
  184. xfdmaster.library/xfdDecrunchSegment     xfdmaster.library/xfdDecrunchSegment
  185.  
  186.    NAME
  187.     xfdDecrunchSegment -- Decrunch a file from its segment list.
  188.  
  189.    SYNOPSIS
  190.     success = xfdDecrunchSegment(segmentinfo)
  191.       D0             -72             A0
  192.  
  193.     BOOL xfdDecrunchSegment(struct xfdSegmentInfo *);
  194.  
  195.    FUNCTION
  196.     Decrunches a segment list. You have to call xfdRecogSegment()
  197.     first, only if this call was successful, you may call
  198.     xfdDecrunchSegment().
  199.  
  200.     You have to init the xfdsi_Special field with a pointer to a
  201.     special info buffer if any special flags are set in the
  202.     xfdsi_PackerFlags field:
  203.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  204.                  password is stored in xfdsi_MaxSpecialLen,
  205.                  if this is -1, password is not limited).
  206.     XFDPFB_KEY16 (V35) - xfdsi_Special points to an UWORD that holds
  207.                          a 16 bit key.
  208.     XFDPFB_KEY32 (V35) - xfdsi_Special points to an ULONG that holds
  209.                          a 32 bit key.
  210.  
  211.     (V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set,
  212.     initialize xfdsi_RelMode with the desired XFDREL_#? value.
  213.  
  214.     If decrunching was successful, xfdsi_SegList holds a BPTR to
  215.     the decrunched segment list. The old segment list has been
  216.     released and/or replaced by the new one (depends on cruncher).
  217.  
  218.     If decrunching failed, xfdsi_SegList may be NULL. This happens
  219.     if an error occured after the seglist has already been changed
  220.     in any way. It then will be released.
  221.     Otherwise, if xfdsi_SegList is not NULL, it still contains a
  222.     valid BPTR to the crunched segment list.
  223.  
  224.    INPUTS
  225.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  226.        xfdsi_Special - Pointer to special info if required.
  227.        xfdsi_RelMode - (V34) XFDREL_#? value if required.
  228.  
  229.    RESULT
  230.     success - TRUE if decrunching was successful, FALSE if
  231.               anything went wrong.
  232.  
  233.    NOTE
  234.     If you no longer need the decrunched segment list, you may
  235.     release it by simply calling dos.library/UnloadSeg().
  236.  
  237.    SEE ALSO
  238.     xfdRecogSegment(), dos.library/UnloadSeg()
  239.  
  240. xfdmaster.library/xfdFreeBufferInfo       xfdmaster.library/xfdFreeBufferInfo
  241.  
  242.    NAME
  243.     xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure.
  244.  
  245.    SYNOPSIS
  246.     xfdFreeBufferInfo(bufferinfo)
  247.            -36            A1
  248.  
  249.     void xfdFreeBufferInfo(struct xfdBufferInfo *);
  250.  
  251.    FUNCTION
  252.     Deallocates the memory reserved via xfdAllocBufferInfo().
  253.  
  254.     (V36) This function is obsolete and shouldn't be used with new
  255.     code any longer. Use xfdFreeObject() instead.
  256.  
  257.    INPUTS
  258.     bufferinfo - Pointer to xfdBufferInfo structure.
  259.  
  260.    RESULT
  261.     None.
  262.  
  263.    SEE ALSO
  264.     xfdAllocBufferInfo(), xfdAllocObject()
  265.  
  266. xfdmaster.library/xfdFreeObject               xfdmaster.library/xfdFreeObject
  267.  
  268.    NAME
  269.     xfdFreeObject -- Free memory of object. (V36)
  270.  
  271.    SYNOPSIS
  272.     xfdFreeObject(object)
  273.         -120        A1
  274.  
  275.     void xfdFreeObject(object *);
  276.  
  277.    FUNCTION
  278.     Deallocates the memory reserved via xfdAllocObject().
  279.  
  280.    INPUTS
  281.     object - Pointer to object.
  282.  
  283.    RESULT
  284.     None.
  285.  
  286.    SEE ALSO
  287.     xfdAllocObject()
  288.  
  289. xfdmaster.library/xfdFreeScanList           xfdmaster.library/xfdFreeScanList
  290.  
  291.    NAME
  292.     xfdFreeScanList -- Free linked list of xfdScanNode structures. (V37)
  293.  
  294.    SYNOPSIS
  295.     xfdFreeScanList(scannode)
  296.          -144          A1
  297.  
  298.     void xfdFreeScanList(struct xfdScanNode *);
  299.  
  300.    FUNCTION
  301.     Deallocates the memory of all xfdScanNode structures that have been
  302.     returned as result by xfdScanData().
  303.  
  304.    INPUTS
  305.     scannode - Pointer to the first xfdScanNode structure.
  306.  
  307.    RESULT
  308.     None.
  309.  
  310. xfdmaster.library/xfdFreeSegmentInfo     xfdmaster.library/xfdFreeSegmentInfo
  311.  
  312.    NAME
  313.     xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure.
  314.  
  315.    SYNOPSIS
  316.     xfdFreeSegmentInfo(segmentinfo)
  317.            -48             A1
  318.  
  319.     void xfdFreeSegmentInfo(struct xfdSegmentInfo *);
  320.  
  321.    FUNCTION
  322.     Deallocates the memory reserved via xfdAllocSegmentInfo().
  323.  
  324.     (V36) This function is obsolete and shouldn't be used with new
  325.     code any longer. Use xfdFreeObject() instead.
  326.  
  327.    INPUTS
  328.     segmentinfo - Pointer to xfdSegmentInfo structure.
  329.  
  330.    RESULT
  331.     None.
  332.  
  333.    SEE ALSO
  334.     xfdAllocSegmentInfo(), xfdAllocObject()
  335.  
  336. xfdmaster.library/xfdGetErrorText           xfdmaster.library/xfdGetErrorText
  337.  
  338.    NAME
  339.     xfdGetErrorText -- Get an ascii string from an error number.
  340.  
  341.    SYNOPSIS
  342.     string = xfdGetErrorText(error)
  343.       D0           -78        D0.w
  344.  
  345.     STRPTR xfdGetErrorText(UWORD);
  346.  
  347.    FUNCTION
  348.     Whenever a library call fails, you receive an error number either
  349.     in the xfd#?_Error field or directly as a returncode. This function
  350.     gets the corresponding ascii string to the occured error.
  351.  
  352.    INPUTS
  353.     error - Error number from xfd#?_Error or returncode.
  354.  
  355.    RESULT
  356.     string - Pointer to an ascii string that describes the error.
  357.  
  358. xfdmaster.library/xfdInitScanHook           xfdmaster.library/xfdInitScanHook
  359.  
  360.    NAME
  361.     xfdInitScanHook -- Allocate and init xfdScanHook structure. (V37)
  362.  
  363.    SYNOPSIS
  364.     scanhook = xfdInitScanHook(entry, data)
  365.        D0           -156         A0    A1
  366.  
  367.     struct xfdScanHook *xfdInitScanHook(APTR, APTR);
  368.  
  369.    FUNCTION
  370.     Allocates a xfdScanHook structure and fills the xfdsh_Entry and
  371.     xfdsh_Data fields with the given arguments.
  372.     You may do these two steps by yourself using xfdAllocObject(), but
  373.     this method is just easier.
  374.  
  375.    INPUTS
  376.     entry - The entrypoint of your hook code. Note that only registers
  377.             D0/D1/A0/A1 may be scratched, all others have to be saved.
  378.     data  - Pointer to some data that might be useful for the execution
  379.             of your hook code.
  380.  
  381.    RESULT
  382.     scanhook - Pointer to the xfdScanHook structure or NULL if there
  383.                occured an error.
  384.  
  385.    NOTE
  386.     You have to release the memory of this structure if you don't
  387.     need it any longer with xfdFreeObject().
  388.  
  389.    SEE ALSO
  390.     xfdAllocObject(), xfdFreeObject(), xfdScanData()
  391.  
  392. xfdmaster.library/xfdObjectType               xfdmaster.library/xfdObjectType
  393.  
  394.    NAME
  395.     xfdObjectType -- Determine type of object. (V37)
  396.  
  397.    SYNOPSIS
  398.     objecttype = xfdObjectType(object)
  399.         D0            -150       A1
  400.  
  401.     ULONG xfdObjectType(object *);
  402.  
  403.    FUNCTION
  404.     Checks if object points to a XFDOBJ_#? object and returns the type
  405.     of this object if possible.
  406.  
  407.    INPUTS
  408.     object - Pointer to a possible XFDOBJ_#? object.
  409.  
  410.    RESULT
  411.     objecttype - One of the XFDOBJ_#? values or NULL if not an object.
  412.  
  413.    SEE ALSO
  414.     xfdAllocObject()
  415.  
  416. xfdmaster.library/xfdRecogBuffer             xfdmaster.library/xfdRecogBuffer
  417.  
  418.    NAME
  419.     xfdRecogBuffer -- Examine buffer for crunched file.
  420.  
  421.    SYNOPSIS
  422.     success = xfdRecogBuffer(bufferinfo)
  423.       D0             -54         A0
  424.  
  425.     BOOL xfdRecogBuffer(struct xfdBufferInfo *);
  426.  
  427.    FUNCTION
  428.     Examines a file for known crunchers. You pass a pointer to
  429.     the file buffer in xfdbi_SourceBuffer and the length of the
  430.     buffer in xfdbi_SourceBufLen.
  431.  
  432.     (V37) You may additionally set some flags in xfdbi_Flags:
  433.     XFDFB_RECOGEXTERN   - If this flag is set, the external slaves
  434.                           will be used for recognition, otherwise
  435.                           they will be ignored.
  436.  
  437.     If a crunched file has been recognized, the following fields
  438.     in the xfdBufferInfo structure will be initialized:
  439.  
  440.     xfdbi_PackerName    - Pointer to the name of the cruncher.
  441.     xfdbi_PackerFlags   - Contains the packer type and additional
  442.                           information (eg. password).
  443.     xfdbi_MaxSpecialLen - Only used if any special flags are set.
  444.  
  445.    INPUTS
  446.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  447.        xfdbi_SourceBuffer - Pointer to file buffer.
  448.        xfdbi_SourceBufLen - Length of file buffer.
  449.        (V37) xfdbi_Flags  - Flags for recognition.
  450.  
  451.    RESULT
  452.     success - TRUE if a cruncher has been recognized, FALSE if
  453.               file is unknown.
  454.  
  455.    SEE ALSO
  456.     xfdDecrunchBuffer()
  457.  
  458.    NOTE
  459.     The behaviour concerning external slaves has changed for V37.
  460.     This was neccessary as there exist a lot of external slaves that
  461.     are not coded properly. The XFDFB_RECOGEXTERN flag has been
  462.     introduced to avoid problems unless the user really wants to use
  463.     external recognition.
  464.  
  465. xfdmaster.library/xfdRecogLinker             xfdmaster.library/xfdRecogLinker
  466.  
  467.    NAME
  468.     xfdRecogLinker -- Examine buffer for linked file. (V36)
  469.  
  470.    SYNOPSIS
  471.     success = xfdRecogLinker(linkerinfo)
  472.       D0           -126          A0
  473.  
  474.     BOOL xfdRecogLinker(struct xfdLinkerInfo *);
  475.  
  476.    FUNCTION
  477.     Examines a file for known link mechanisms. You pass a pointer to
  478.     the file buffer in xfdli_Buffer and the length of the buffer in
  479.     xfdli_BufLen.
  480.  
  481.     If a linked file has been recognized, the following fields
  482.     in the xfdLinkerInfo structure will be initialized:
  483.  
  484.     xfdli_LinkerName - Pointer to the name of the linker.
  485.  
  486.    INPUTS
  487.     linkerinfo - Pointer to an initialized xfdLinkerInfo structure:
  488.        xfdli_Buffer - Pointer to file buffer.
  489.        xfdli_BufLen - Length of file buffer.
  490.  
  491.    RESULT
  492.     success - TRUE if a linker has been recognized, FALSE if
  493.               file is unknown.
  494.  
  495.    SEE ALSO
  496.     xfdUnlink()
  497.  
  498. xfdmaster.library/xfdRecogSegment           xfdmaster.library/xfdRecogSegment
  499.  
  500.    NAME
  501.     xfdRecogSegment -- Examine segment list for crunched file.
  502.  
  503.    SYNOPSIS
  504.     success = xfdRecogSegment(segmentinfo)
  505.       D0             -66          A0
  506.  
  507.     BOOL xfdRecogSegment(struct xfdSegmentInfo *);
  508.  
  509.    FUNCTION
  510.     Examines a segment list for known crunchers. You pass a BPTR
  511.     to the segment list in xfdsi_SegList.
  512.  
  513.     (V37) You may additionally set some flags in xfdsi_Flags:
  514.     XFDFB_RECOGEXTERN   - If this flag is set, the external slaves
  515.                           will be used for recognition, otherwise
  516.                           they will be ignored.
  517.  
  518.     If a crunched segment list has been recognized, the following
  519.     fields in the xfdSegmentInfo structure will be initialized:
  520.  
  521.     xfdsi_PackerName    - Pointer to the name of the cruncher.
  522.     xfdsi_PackerFlags   - Contains the packer type and additional
  523.                           information (eg. password).
  524.     xfdsi_MaxSpecialLen - Only used if any special flags are set.
  525.  
  526.    INPUTS
  527.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  528.        xfdsi_SegList     - BPTR to segment list.
  529.        (V37) xfdsi_Flags - Flags for recognition.
  530.  
  531.    RESULT
  532.     success - TRUE if a cruncher has been recognized, FALSE if
  533.               segment list is unknown.
  534.  
  535.    SEE ALSO
  536.     xfdDecrunchSegment()
  537.  
  538. xfdmaster.library/xfdRelocate                   xfdmaster.library/xfdRelocate
  539.  
  540.    NAME
  541.     xfdRelocate -- Create segment list from file buffer. (V34)
  542.  
  543.    SYNOPSIS
  544.     error = xfdRelocate(buffer, length, result, mode)
  545.      D0.w       -96       A0      D0      A1    D1.w
  546.  
  547.     UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD);
  548.  
  549.    FUNCTION
  550.     Creates a relocated and fully executable segment list from
  551.     a file buffer. The result is a BPTR to the first segment,
  552.     similar to the result of a call to dos.library/LoadSeg().
  553.  
  554.    INPUTS
  555.     buffer - Pointer to the file buffer that should be relocated.
  556.     length - Length of the file buffer.
  557.     result - Pointer to the longword that should hold the result.
  558.     mode   - Any XFDREL_#? relocation mode.
  559.  
  560.    RESULT
  561.     error  - XFDERR_OK if no error occured, else XFDERR_#?.
  562.     result - Holds a BPTR to the first segment if error = XFDERR_OK.
  563.  
  564.    NOTE
  565.     There is no need to call xfdTestHunkStructure[New|Flags]() before
  566.     relocation because xfdRelocate() does this already.
  567.  
  568.     This routine supports the following hunk types:
  569.     - hunk_name         ($3e8) -> Skipped.
  570.     - hunk_code         ($3e9) -> Creates new code segment.
  571.     - hunk_data         ($3ea) -> Creates new data segment.
  572.     - hunk_bss          ($3eb) -> Creates new bss segment.
  573.     - hunk_reloc32      ($3ec) -> Used for relocation.
  574.     - hunk_symbol       ($3f0) -> Skipped.
  575.     - hunk_debug        ($3f1) -> Skipped.
  576.     - hunk_end          ($3f2) -> May be left out.
  577.     - hunk_header       ($3f3) -> Only at top of file.
  578.     - hunk_reloc32short ($3f7/$3fc) -> Used for relocation.
  579.     Any other hunk types create an error. There is no support for
  580.     hunk_overlay, because the main purpose of this routine is to
  581.     be called from xfds_DecrunchSegment. And in that case, the real
  582.     dos.library/LoadSeg() has already initialized the overlay header.
  583.  
  584. xfdmaster.library/xfdScanData                   xfdmaster.library/xfdScanData
  585.  
  586.    NAME
  587.     xfdScanData -- Scan buffer for crunched data areas. (V37)
  588.  
  589.    SYNOPSIS
  590.     error = xfdScanData(buffer, length, result, flags, scanhook)
  591.      D0.w      -138       A0      D0      A1     D1.w     A2
  592.  
  593.     UWORD xfdScanData(APTR, ULONG, ULONG *, UWORD, struct xfdScanHook *);
  594.  
  595.    FUNCTION
  596.     Scans the buffer for any crunched data and returns a linked list
  597.     of xfdScanNode structures if one or more data files have been found.
  598.  
  599.     Flags can be one or more of these:
  600.     XFDSDF_USEEXTERN - Use external slaves for scanning.
  601.     XFDSDF_SCANODD   - Scan at odd addresses (only if CPU = 68020+)
  602.  
  603.     If you submit a xfdScanHook structure, you should initialize it
  604.     using xfdInitScanHook(). After every scanned byte (or word if
  605.     odd scanning is not used) your hook function will be called and
  606.     given an APTR to its own xfdScanHook structure in register A0.
  607.     You may or may not use any information from the structure in your
  608.     hook code and then set a returncode in D0 (TRUE to continue
  609.     scanning or FALSE to abort).
  610.     The xfdsh_ToDo field contains the amount of bytes that still have
  611.     to be scanned. The value is taken after a scan attempt has been
  612.     performed. Additionally, if the last scan attempt leaded to a
  613.     result, xfdsh_ScanNode contains a pointer to the respective
  614.     xfdScanNode structure.
  615.  
  616.     You may use the hook for several things, eg. just to test for a
  617.     break signal or a pressed gadget, as a progress indicator or to
  618.     print detected data immediately instead of waiting until the end
  619.     of the scan.
  620.  
  621.    INPUTS
  622.     buffer   - Pointer to the buffer that should be scanned.
  623.     length   - Length of the buffer.
  624.     result   - Pointer to the longword that should hold the pointer
  625.                to the first xfdScanNode structure.
  626.     flags    - One or more XFDSDB_#? scan flags.
  627.     scanhook - Pointer to initialized xfdScanHook structure or NULL.
  628.  
  629.    RESULT
  630.     error  - XFDERR_OK if no error occured,
  631.              XFDERR_HOOKBREAK if hook returned FALSE,
  632.              else XFDERR_#?.
  633.     result - Holds pointer to the first xfdScanNode structure or NULL
  634.              if nothing was found. This is only valid if error is either
  635.              XFDERR_OK or XFDERR_HOOKBREAK.
  636.  
  637.    SEE ALSO
  638.     xfdInitScanHook()
  639.  
  640. xfdmaster.library/xfdStripHunks               xfdmaster.library/xfdStripHunks
  641.  
  642.    NAME
  643.     xfdStripHunks -- Remove annoying hunks from file buffer. (V36)
  644.  
  645.    SYNOPSIS
  646.     error = xfdStripHunks(buffer, length, result, flags)
  647.      D0.w       -108        A0      D0      A1    D1.w
  648.  
  649.     UWORD xfdStripHunks(APTR, ULONG, ULONG *, UWORD);
  650.  
  651.    FUNCTION
  652.     Strips hunk_name, hunk_symbol and hunk_debug from file buffer.
  653.     This might be useful to shorten executables, but the main
  654.     purpose is to remove decrunch protections based on modified
  655.     hunk structures.
  656.  
  657.    INPUTS
  658.     buffer - Pointer to the file buffer that should be stripped.
  659.     length - Length of the file buffer.
  660.     result - Pointer to the longword that should hold the new
  661.              file length after stripping.
  662.     flags  - One or more XFDSHB_#? strip flags.
  663.  
  664.    RESULT
  665.     error  - XFDERR_OK if no error occured, else XFDERR_#?.
  666.     result - Holds new length of file if error = XFDERR_OK.
  667.  
  668.    NOTE
  669.     There is no need to call xfdTestHunkStructure[New|Flags]() before
  670.     stripping because xfdStripHunks() does this already.
  671.  
  672.     Attention! The new file length given as a result may be used
  673.     to save the modified file to disk, but the length of the
  674.     buffer itself is still the same as it was before the call.
  675.  
  676.     This routine supports the following hunk types:
  677.     - hunk_name         ($3e8) -> Stripped on XFDSHB_NAME.
  678.     - hunk_code         ($3e9) -> Skipped.
  679.     - hunk_data         ($3ea) -> Skipped.
  680.     - hunk_bss          ($3eb) -> Skipped.
  681.     - hunk_reloc32      ($3ec) -> Skipped.
  682.     - hunk_symbol       ($3f0) -> Stripped on XFDSHB_SYMBOL.
  683.     - hunk_debug        ($3f1) -> Stripped on XFDSHB_DEBUG.
  684.     - hunk_end          ($3f2) -> Skipped.
  685.     - hunk_header       ($3f3) -> Only at top of file.
  686.     - hunk_reloc32short ($3f7/$3fc) -> Skipped.
  687.     Any other hunk types create an error.
  688.  
  689. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
  690.  
  691.    NAME
  692.     xfdTestHunkStructure -- Test hunks of executable file.
  693.  
  694.    SYNOPSIS
  695.     success = xfdTestHunkStructure(buffer, length)
  696.       D0              -84            A0      D0
  697.  
  698.     BOOL xfdTestHunkStructure(APTR, ULONG);
  699.  
  700.    FUNCTION
  701.     Checks an executable file for a valid hunk structure.
  702.     This is important for decrunching files, because an incomplete
  703.     or damaged file may cause a system crash.
  704.  
  705.    INPUTS
  706.     buffer - Pointer to the file buffer that should be checked.
  707.     length - Length of the file buffer.
  708.  
  709.    RESULT
  710.     success - TRUE if file is ok, FALSE if file is damaged.
  711.  
  712.    NOTE
  713.     It is recommended to use xfdTestHunkStructureNew() instead of
  714.     this routine for a more detailed error description. Internally
  715.     both calls use the same routines, this one is only left here
  716.     for downward compatibility.
  717.  
  718.    SEE ALSO
  719.     xfdTestHunkStructureNew(), xfdTestHunkStructureFlags()
  720.  
  721. xfdmaster.l/xfdTestHunkStructureFlags   xfdmaster.l/xfdTestHunkStructureFlags
  722.  
  723.    NAME
  724.     xfdTestHunkStructureFlags -- Test hunks of executable file. (V36)
  725.  
  726.    SYNOPSIS
  727.     error = xfdTestHunkStructureFlags(buffer, length, flags)
  728.      D0.w            -102               A0      D0     D1.w
  729.  
  730.     UWORD xfdTestHunkStructureFlags(APTR, ULONG, UWORD);
  731.  
  732.    FUNCTION
  733.     Checks an executable file for a valid hunk structure and reacts
  734.     on certain hunk types if special flags are given.
  735.     This is important for decrunching files, because an incomplete
  736.     or damaged file may cause a system crash.
  737.  
  738.    INPUTS
  739.     buffer - Pointer to the file buffer that should be checked.
  740.     length - Length of the file buffer.
  741.     flags  - Flags to cause special actions on certain hunk types.
  742.              These are:
  743.              XFDTHB_NOOVERLAYS - forces error on hunk_overlay.
  744.  
  745.    RESULT
  746.     error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged
  747.             or special flags got activated.
  748.  
  749.    NOTE
  750.     You don't have to call this function before trying to decrunch
  751.     a file, because xfdDecrunchBuffer() does this already.
  752.  
  753.     This hunk checker supports the following hunk types:
  754.     - hunk_name         ($3e8)
  755.     - hunk_code         ($3e9)
  756.     - hunk_data         ($3ea)
  757.     - hunk_bss          ($3eb)
  758.     - hunk_reloc32      ($3ec)
  759.     - hunk_symbol       ($3f0)
  760.     - hunk_debug        ($3f1)
  761.     - hunk_end          ($3f2)
  762.     - hunk_header       ($3f3)
  763.     - hunk_overlay      ($3f5) -> forces error on XFDTHB_NOOVERLAYS
  764.     - hunk_break        ($3f6)
  765.     - hunk_reloc32short ($3f7/$3fc)
  766.     It recognizes the standard hunk_overlay ($3f5) format and some
  767.     user-defined overlay types too. Anyway, it may happen that some
  768.     weird overlay hunk causes problems because there isn't any real
  769.     definition for overlays.
  770.     The hunk structure of a non-overlayed file will nevertheless
  771.     be checked 100% correctly.
  772.  
  773.    SEE ALSO
  774.     xfdTestHunkStructureNew()
  775.  
  776. xfdmaster.lib/xfdTestHunkStructureNew   xfdmaster.lib/xfdTestHunkStructureNew
  777.  
  778.    NAME
  779.     xfdTestHunkStructureNew -- Test hunks of executable file. (V34)
  780.  
  781.    SYNOPSIS
  782.     error = xfdTestHunkStructureNew(buffer, length)
  783.      D0.w           -90               A0      D0
  784.  
  785.     UWORD xfdTestHunkStructureNew(APTR, ULONG);
  786.  
  787.    FUNCTION
  788.     Checks an executable file for a valid hunk structure.
  789.     This is important for decrunching files, because an incomplete
  790.     or damaged file may cause a system crash.
  791.  
  792.    INPUTS
  793.     buffer - Pointer to the file buffer that should be checked.
  794.     length - Length of the file buffer.
  795.  
  796.    RESULT
  797.     error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged.
  798.  
  799.    NOTE
  800.     This is actually just a call to xfdTestHunkStructureFlags()
  801.     with no flags set.
  802.  
  803.    SEE ALSO
  804.     xfdTestHunkStructureFlags()
  805.  
  806. xfdmaster.library/xfdUnlink                       xfdmaster.library/xfdUnlink
  807.  
  808.    NAME
  809.     xfdUnlink -- Unlink two files inside the same buffer. (V36)
  810.  
  811.    SYNOPSIS
  812.     success = xfdUnlink(linkerinfo)
  813.       D0        -132        A0
  814.  
  815.     BOOL xfdUnlink(struct xfdLinkerInfo *);
  816.  
  817.    FUNCTION
  818.     Unlinks two files that have been joined by some so-called
  819.     4EB9-Linker. No new buffers are created, unlinked files are both
  820.     located inside source buffer. You have to call xfdRecogLinker()
  821.     first, only if this call was successful, you may call xfdUnlink().
  822.  
  823.     If unlinking was successful, the following fields in the
  824.     xfdLinkerInfo structure will be initialized:
  825.  
  826.     xfdli_Save1    - Pointer to first unlinked file.
  827.     xfdli_Save2    - Pointer to second unlinked file.
  828.     xfdli_SaveLen1 - Length of first unlinked file.
  829.     xfdli_SaveLen2 - Length of second unlinked file.
  830.  
  831.    INPUTS
  832.     linkerinfo - Pointer to an initialized xfdLinkerInfo structure
  833.                  as received by xfdRecogLinker().
  834.  
  835.    RESULT
  836.     success - TRUE if unlinking was successful, FALSE if
  837.               anything went wrong.
  838.  
  839.    NOTE
  840.     After a call to xfdUnlink(), the contents of xfdli_Buffer are
  841.     under no circumstances valid any longer. The only way to make use
  842.     of the buffer contents is via xfdli_Save1 and xfdli_Save2.
  843.     But if you have finished work with the splitted files, you have
  844.     to release exactly the memory you have allocated for xfdli_Buffer.
  845.  
  846.     There exist several programs that produce the same linker output.
  847.     Some of them are very badly programmed, so if unlinking fails or
  848.     produces non-executable files, don't blame xfdmaster.library.
  849.  
  850.    SEE ALSO
  851.     xfdRecogLinker()
  852.